.TH "display-vnc" 7 "2009-09-22" "libggi-current" GGI
.SH NAME
\fBdisplay-vnc\fR : Display on vnc client over a network
.SH SYNOPSIS
.nb
.nf
display-vnc: [-bind=<iface>] [-cert=<file>] [-ciphers=<list>]
             [-client=<host>] [-copyrect=no|always] [-corre=no]
             [-deskname=no] [-desksize=no] [-dh=<file>]
             [-display=<dpy>] [-gii=no] [-hextile=no] [-kold]
             [-passwd=<file>] [-physz=<sizex>,<sizey>[dpi]]
             [-privkey=<file>] [-rre=no] [-server[=<dpy>|stdio]]
             [-sslver=<method>] [-stdio] [-tight=enc|ext|no]
             [-title=<title>] [-trle=no] [-vencrypt]
             [-vrfydir=<dir>] [-vrfyfile=<file>] [-viewonly]
             [-viewpw=<file>] [-wmvi=no] [-zlib=<level>|no]
             [-zlibhex=<level>|no] [-zrle=<level>|no]
.fi

.SH DESCRIPTION
Provides a linear framebuffer in main memory. A vnc client that
connects gets to see a copy of this framebuffer. The protocol
used is the remote framebuffer protocol, or the RFB protocol for
short.

The supported RFB protocol versions are 3.3, 3.7 and 3.8.
.SH OPTIONS
.TP
\f(CW-bind=<iface>\fR
Bind the server socket to the specific \fIiface\fR, e.g. 127.0.0.1 in
case display-vnc should only accept connections from an ssh tunnel.

.TP
\f(CW-cert=<file>\fR
This option is only in effect if the \fI-vencrypt\fR option is also given.
PEM-format \fIfile\fR with the certificate chain to use. By giving this
option you also switch from using anonymous TLS to using x509
certificates. In order to use the certificate chain, you may also have to
load a private key, using the \fI-privkey\fR option.

.TP
\f(CW-ciphers=<list>\fR
This option is only in effect if the \fI-vencrypt\fR option is also given.
Explicitely specify the allowed cipher suites (in the same format OpenSSL
uses, see the openssl ciphers manpage). The default allowed ciphers are
\fBaNULL:!eNULL:@STRENGTH\fR (all anonymous ciphers that provides encryption),
unless the \fI-cert\fR option is also given in which case the default is
instead \fBALL:!aNULL:@STRENGTH\fR (all encrypting ciphers that are not
anonymous).

.TP
\f(CW-client=<host>\fR
Make a connection to \fIhost\fR, instead of waiting for clients to
connect. A vnc viewer in listening mode is expected to be found on
\fIhost\fR.

.TP
\f(CW-copyrect=no|always\fR
Controls when the CopyRect encoding is used. Select \fIno\fR to disable
it completely, and \fIalways\fR to enable it when suitable even if there
is support for some other encoding the client has preferred. The default
is to only use the CopyRect encoding if it is the most preferred
encoding available.

.TP
\f(CW-corre=no\fR
Disables the CoRRE encoding.

.TP
\f(CW-deskname=no\fR
Disables the DesktopName pseudo-encoding.

.TP
\f(CW-desksize=no\fR
Disables the DesktopSize pseudo-encoding.

.TP
\f(CW-dh=<file>\fR
This option is only in effect if the \fI-vencrypt\fR option is also given.
Specify a PEM file with diffie-hellman parameters to use. If this option
is not used, DH parameters will be generated on-the-fly which may be
somewhat time consuming. See the openssl dhparam manpage for how to
generate a DH PEM file.

.TP
\f(CW-display=<dpy>\fR
The display number clients should connect to. Display number 0 is
equivalent to tcp port 5900.

If the \fI-client\fR option is also given, this is instead the display
number this server connects to, and display number 0 is equivalent
to tcp port 5500 in that case.

.TP
\f(CW-gii=no\fR
Disables the gii pseudo-encoding.

.TP
\f(CW-hextile=no\fR
Disables the hextile encoding.

.TP
\f(CW-kold\fR
Kill On Last Disconnect. This option ends the application when the last
client disconnects. It can be useful in conjunction with the \fI-client\fR,
\fI-stdio\fR and \fI-server=stdio\fR options so that the application does
not linger without any user feedback.

.TP
\f(CW-passwd=<file>\fR
The vnc client has to successfully encrypt a random challenge with
the password stated on the first line of \fIfile\fR in order to connect.
In the password, only the eight first characters and the seven least
significant bits of every character are used in the authentication.
If this password is given, the client is allowed to send input events
such as keys and pointer movements to the application. However, this
allowance may be overridden with the \fI-viewonly\fR option. See the
options \fI-viewonly\fR and \fI-viewpw\fR for comparison.

.TP
\f(CW-physz=<sizex>,<sizey>[dpi]\fR
This option will provide a physical screen size for applications
which wish to remain resolution independent. \fIsizex\fR,:p:\fBsizey\fR
are the x,y size of the screen in millimeters, unless the optional
\f(CWdpi\fR string is affixed, in which case, they represent resolution
in dots-per-inch.

.TP
\f(CW-privkey=<file>\fR
This option is only in effect if the \fI-vencrypt\fR option is also given.
PEM-format \fIfile\fR with the private key for the certificate chain given
with the \fI-cert\fR option. The private key may (unfortunately) not be
protected with a pass phrase, since there is no good way to pass the
key to display-vnc.

.TP
\f(CW-rre=no\fR
Disables the RRE encoding.

.TP
\f(CW-server[=<dpy>|stdio]\fR
To run both a server and open a client at the same time, but with
different display numbers, the server display number can be specified
using \fI-server=<dpy>\fR. If no argument is given, the display number
is collected for the \fI-display\fR option. Use \fI-display=stdio\fR to
accept connections from the stdin file handle, which is suitable for
serving a GGI application as an inetd(8) \fIwait\fR type service (see
the example below). The \fI-server=stdio\fR option is incompatible with
the \fI-stdio\fR option.

.TP
\f(CW-sslver=<method>\fR
This option is only in effect if the \fI-vencrypt\fR option is also given.
The SSL \fImethod\fR can be one of SSLv2, SSLv3, TLSv1 or SSLv23 (allows
a mix). TLSv1 is the default, since SSLv2 has security issues.

.TP
\f(CW-stdio\fR
Talk the RFB protocol on stdin/stdout instead of waiting for clients
to connect. Suitable for serving a GGI application as an inetd(8)
\fInowait\fR type service (see the example below). One requirement
though, is that the served GGI application does not "chatter" on
stdout and/or stderr. The \fI-stdio\fR option is incompatible with the
\fI-server=stdio\fR option.

.TP
\f(CW-tight=enc|ext|no\fR
Control the Tight encoding and the Tight protocol extension. Using
\fI-tight=enc\fR enables the Tight encoding, using \fI-tight=ext\fR
enables the Tight protocol extension, and \fI-tight=no\fR disables
them both. The default is to enable both the Tight encoding and the
Tight protocol extension.

.TP
\f(CW-title=<title>\fR
The \fItitle\fR clients should use on their windows. If this option
is not specified, the default is "GGI on vnc".

.TP
\f(CW-trle=no\fR
Disables the TRLE encoding.

.TP
\f(CW-vencrypt\fR
Enable the VeNCrypt protocol extension and require that it is used. By
default the VeNCrypt extension will use anonymous encryption (susceptible
to man in the middle attacks). If the \fI-cert\fR option is given VeNCrypt
will instead issue an x509 certificate for the client to verify. In
addition to that, display-vnc will require the client to provide an x509
certificate if any or both of the \fI-vrfyfile\fR or \fI-vrfydir\fR options
are given.

.TP
\f(CW-vrfydir=<dir>\fR
This option is only in effect if the \fI-vencrypt\fR and \fI-cert\fR options
are also given.
Directory with PEM-format certificate authorities. The CA are used when
verifying the client certificate. If this option (or the \fI-vrfydir\fR
option) is not given, the client is not required to provide a valid
certificate.

.TP
\f(CW-vrfyfile=<file>\fR
This option is only in effect if the \fI-vencrypt\fR and \fI-cert\fR options
are also given.
PEM-format file with certificate authorities. The CA are used when
verifying the client certificate. If this option (or the \fI-vrfyfile\fR
option) is not given, the client is not required to provide a valid
certificate.

.TP
\f(CW-viewonly\fR
If this option is given, no client is allowed to send input events
such as keys and pointer movements to the application. If the
\fI-passwd\fR option has also been given, the given password is
effectively reduced to a \fI-viewpw\fR password. This option is
intended for use together with e.g. the \f(CWdisplay-multi(7)\fR
target.

.TP
\f(CW-viewpw=<file>\fR
The vnc client has to successfully encrypt a random challenge with
the password stated on the first line of \fIfile\fR in order to connect.
In the password, only the eight first characters and the seven least
significant bits of every character are used in the authentication.
If this password is given, the client is \fInot\fR allowed to send input
events such as keys and pointer movements to the application. See
the options \fI-passwd\fR and \fI-viewonly\fR for comparison.

.TP
\f(CW-wmvi=no\fR
Disables the WMVi pseudo-encoding.

.TP
\f(CW-zlib=<level>|no\fR
Specify the compression level to use for the Zlib encoding. 0 for
no compression and 9 for maximum compression. Saying \fIno\fR here
disables the Zlib encoding. If the option isn't specified, a default
compromize between speed and compression is selected.

.TP
\f(CW-zlibhex=<level>|no\fR
Specify the compression level to use for the ZlibHex encoding. 0 for
no compression and 9 for maximum compression. Saying \fIno\fR here
disables the ZlibHex encoding. If the option isn't specified, a default
compromize between speed and compression is selected.

.TP
\f(CW-zrle=<level>|no\fR
Specify the compression level to use for the ZRLE encoding. 0 for
no compression and 9 for maximum compression. Saying \fIno\fR here
disables the ZRLE encoding. If the option isn't specified, a default
compromize between speed and compression is selected.

.PP
.SH FEATURES
.IP \(bu 4
Raw, CopyRect, RRE, CoRRE, Hextile, Tight, Zlib, ZlibHex, TRLE and ZRLE
encodings. The CopyRect encoding is only used for panning.
.IP \(bu 4
DesktopName, DesktopSize, GII and WMVi pseudo-encodings.
.IP \(bu 4
Support for the Tight protocol extension from the TightVNC project.
.IP \(bu 4
Support for the VeNCrypt protocol extension from the VeNCrypt project.
However, the VeNCrypt \fBplain\fR authentication is not supported.
.IP \(bu 4
Multiple simultaneous clients (shared session).
.IP \(bu 4
DirectBuffer always available, including tidy buffer mode (see
\f(CWggiSetFlags(3)\fR).
.IP \(bu 4
Multiple frames always available.
.IP \(bu 4
Panning always available.
.IP \(bu 4
Unaccelerated.
.PP
.SH EXAMPLES
To launch a GGI application for each connection made to a TCP port, you
may use inetd(8). Just add a line like this to \f(CW/etc/inetd.conf\fR:

.nb
.nf
vnc stream tcp nowait nobody /path/to/app app -t vnc:-stdio:-kold
.fi

You also need to define what port the service \f(CWvnc\fR should use in the
file \f(CW/etc/services\fR:

.nb
.nf
vnc            5900/tcp
.fi

After you make inetd(8) reread its configuration (e.g. send the -HUP
signal to it), you should be able to run the application with a VNC
viewer of your choice.

If you instead want to have all subsequent connections share one
application instance, change the line in \f(CW/etc/inetd.conf\fR to:

.nb
.nf
vnc stream tcp wait nobody /path/to/app app -t vnc:-server=stdio:-kold
.fi

.RS
\fBNote:\fR
This assumes that the application supports the \f(CW-t\fR option to set
the display target, and that it does not output anything at all on
stdout/stderr. The application will run as the user \f(CWnobody\fR.
.RE
.SH CREDITS
The Tight encoding uses the jpeg library from the Independent JPEG Group.
.SH BUGS
.IP \(bu 4
If the application does not give control to libgii with regular
intervals (i.e. \f(CWgiiEventRead(3)\fR, \f(CWgiiEventPoll(3)\fR or some
wrapper that in turn calls one of these functions) this display target
will not work, or at least not work well.
.IP \(bu 4
For the Tight encoding there are a few tunables left. 1) The "weight"
of the different subencodings needs to be tuned. E.g. the gradient
filter subencoding is never used, even if it should be very good on
"blocky" data. 2) The jpeg quality selection could probably also be
better tuned. 3) The client should be able to select the zlib
compression level.
.IP \(bu 4
Special keys (i.e. shift, escape, etc) needs to be converted.
.PP
